package com.back.controller;
// 声明该类所在的包，controller层负责处理前端请求

import com.back.annotation.AuthCheck;
import com.back.common.BaseResponse;
import com.back.common.DeleteRequest;
import com.back.common.ResultUtils;
import com.back.constant.UserConstant;
import com.back.exception.BusinessException;
import com.back.exception.ErrorCode;
import com.back.exception.ThrowUtils;
import com.back.model.dto.hero.HeroAddRequest;
import com.back.model.dto.hero.HeroQueryRequest;
import com.back.model.dto.hero.HeroUpdateRequest;
import com.back.model.vo.hero.HeroVO;
import com.back.service.HeroService;
import com.baomidou.mybatisplus.core.metadata.IPage;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.List;

/**
 * 英雄接口
 * 这个控制器专门处理与游戏角色(英雄)相关的所有请求
 * 对应前端页面中展示的角色信息，如您提供的"死生之律者"等角色展示页面
 */
@RestController  // 标记这是一个REST风格的控制器，会自动将返回值转换为JSON
@RequestMapping("/hero")  // 所有该控制器的请求路径都以/hero开头
@Slf4j  // 提供日志功能，可通过log变量输出日志
public class HeroController {

    @Resource  // 自动注入HeroService实例，用于调用业务逻辑
    private HeroService heroService;

    // region 增删改查

    /**
     * 创建英雄
     * 对应后台管理功能，用于添加新角色到系统中
     * @RequestBody 注解相当于 “快递员”，自动把前端发来的 JSON（快递盒）转换成 HeroAddRequest 对象
     * @param heroAddRequest 英雄添加请求，包含新角色的所有信息
     * @return 英雄ID，返回新创建角色的唯一标识
     * ThrowUtils：自定义的异常处理工具类，封装了抛异常的逻辑
     * throwIf：该工具类的静态方法，接收两个参数：条件和异常类型
     * heroAddRequest == null：校验条件，如果请求参数对象为空 ErrorCode.PARAMS_ERROR：预定义的错误码枚举，表示参数错误
     *
     */
    @PostMapping("/add")  // 处理POST请求，访问路径为/hero/add（前端如果要调用 “添加英雄” 的功能，必须用 POST 方式访问 http://xxx/hero/add 这个地址
    @AuthCheck(mustRole = UserConstant.ADMIN_ROLE)  // 权限检查，仅管理员可访问
    public BaseResponse<Long> addHero(@RequestBody  HeroAddRequest heroAddRequest) {
        // 检查请求参数是否为空，如果为空则抛出参数错误异常
        ThrowUtils.throwIf(heroAddRequest == null, ErrorCode.PARAMS_ERROR);

        // 调用服务层方法添加英雄，返回新生成的英雄ID
        long heroId = heroService.addHero(heroAddRequest);
        // 将结果包装成统一响应格式并返回
        return ResultUtils.success(heroId);
    }

    /**
     * 删除英雄
     * 对应后台管理功能，用于从系统中删除角色
     *
     * @param deleteRequest 删除请求，包含要删除的角色ID
     * @return 是否删除成功
     */
    @PostMapping("/delete")  // 处理POST请求，路径为/hero/delete
    @AuthCheck(mustRole = UserConstant.ADMIN_ROLE)  // 权限检查，仅管理员可访问
    public BaseResponse<Boolean> deleteHero(@RequestBody DeleteRequest deleteRequest) {
        // 检查请求参数是否有效
        if (deleteRequest == null || deleteRequest.getId() <= 0) {
            throw new BusinessException(ErrorCode.PARAMS_ERROR);
        }

        // 获取要删除的角色ID
        long id = deleteRequest.getId();
        // 调用服务层方法删除英雄
        boolean result = heroService.deleteHero(id);
        // 返回删除结果
        return ResultUtils.success(result);
    }

    /**
     * 更新英雄（仅管理员）
     * 对应后台管理功能，用于更新角色信息
     *
     * @param heroUpdateRequest 英雄更新请求，包含要更新的角色信息
     * @return 是否更新成功
     */
    @PostMapping("/update")  // 处理POST请求，路径为/hero/update
    @AuthCheck(mustRole = UserConstant.ADMIN_ROLE)  // 权限检查，仅管理员可访问
    public BaseResponse<Boolean> updateHero(@RequestBody  HeroUpdateRequest heroUpdateRequest) {
        // 检查请求参数是否有效
        if (heroUpdateRequest == null || heroUpdateRequest.getId() == null) {
            throw new BusinessException(ErrorCode.PARAMS_ERROR);
        }

        // 调用服务层方法更新英雄信息
        boolean result = heroService.updateHero(heroUpdateRequest);
        // 返回更新结果
        return ResultUtils.success(result);
    }

    /**
     * 根据 id 获取英雄（封装类）
     * 用于前端展示单个角色的详细信息，如您提供的"希儿·芙乐艾"详情页
     *
     * @param id 英雄ID，要查询的角色唯一标识
     * @return 英雄VO，包含角色的详细信息，用于前端展示
     */
    @GetMapping("/get/vo")  // 处理GET请求，路径为/hero/get/vo
    public BaseResponse<HeroVO> getHeroVOById(long id) {
        // 检查ID是否有效
        ThrowUtils.throwIf(id <= 0, ErrorCode.PARAMS_ERROR);

        // 调用服务层方法获取英雄详情
        HeroVO heroVO = heroService.getHeroVOById(id);
        // 返回角色详情，供前端页面展示
        return ResultUtils.success(heroVO);
    }

    /**
     * 分页获取英雄列表（仅管理员）
     * 用于后台管理系统展示角色列表，支持分页查询
     *
     * @param heroQueryRequest 查询请求，包含分页参数和查询条件
     * @return 英雄VO分页列表
     */
    @PostMapping("/list/page/vo")  // 处理POST请求，路径为/hero/list/page/vo
    @AuthCheck(mustRole = UserConstant.ADMIN_ROLE)  // 权限检查，仅管理员可访问
    public BaseResponse<IPage<HeroVO>> listHeroVOByPage(@RequestBody HeroQueryRequest heroQueryRequest) {
        // 获取分页参数
        long current = heroQueryRequest.getCurrent();
        long size = heroQueryRequest.getPageSize();
        // 限制每页最大数量，防止爬虫或恶意请求
        ThrowUtils.throwIf(size > 20, ErrorCode.PARAMS_ERROR);

        // 调用服务层方法分页查询英雄列表
        IPage<HeroVO> heroVOIPage = heroService.listHeroVOByPage(heroQueryRequest);
        // 返回分页结果
        return ResultUtils.success(heroVOIPage);
    }

    /**
     * 获取所有英雄列表（用于前端展示）
     * 用于前端页面展示所有角色的列表，如您提供的页面左侧的角色列表
     *
     * @return 英雄VO列表，包含所有角色的基本信息
     */
    @GetMapping("/list/all")  // 处理GET请求，路径为/hero/list/all
    public BaseResponse<List<HeroVO>> getAllHeroVOList() {
        // 调用服务层方法获取所有英雄列表
        List<HeroVO> heroVOList = heroService.getAllHeroVOList();
        // 返回所有角色列表，供前端展示角色列表使用
        return ResultUtils.success(heroVOList);
    }

    // endregion - 代码折叠标记结束

}